FRE Function
 ----------------------------------------------------------------------------


 Action

 Returns a value representing the amount of available memory, depending upon
 a given argument.


 Syntax 1

  FRE( numeric- expression%)

 Syntax 2

  FRE( stringexpression$)


 Remarks

 The argument for  FRE can be either a string or numeric expression . The
 argument  stringexpression$ can be a string literal or a string variable.

 The values returned for the different types of arguments depend on whether
 you are using near strings or far strings, as described in the following
 table.
-----------------------------------------------------------------------------
 Function               Value returned if using   Value returned if using
                        near strings              far strings
 ----------------------------------------------------------------------------
 FRE(a$)                Remaining space inDGROUP  Remaining space in  a$'s
                        (in bytes)                segment (in bytes)

 FRE("string literal")  Remaining space inDGROUP  Remaining space for
                        (in bytes)                temporary strings (in
                                                  bytes)

 FRE(0)                 Remaining space in        Error message. Illegal
                        DGROUP (in bytes)         function call

 FRE(-1)                For DOS, remaining space  For DOS, remaining space
                        (in bytes) in far         (in bytes) in far memory;
                        memory; for OS-2, long    for OS-2, long integer
                        integer 2147483647        2147483647

 FRE(-2)                Remaining stack space     Remaining stack space (in
                        (in bytes)                bytes)
 Function               Value returned if using   Value returned if using
                        near strings              far strings
 ----------------------------------------------------------------------------
                        (in bytes)                bytes)

 FRE(-3)                Remaining space in        Remaining space in
                        expanded memory (in       expanded memory (in
                        kilobytes)                kilobytes)

 FRE(any other no.)     Error message. Illegal    Error message. Illegal
                        function call             function call




 FRE(-2) returns the amount of stack space that was never used by the
 program. For example, suppose a program uses a lot of stack space in a
 recursive procedure and then returns to the main level to execute a FRE(-2).
 The value returned will be the amount of stack space that was never used by
 the program. Any space used by the recursive procedure is considered "used"
 So FRE(-2) enables you to find out at the completion of your program what
 the worst-case stack usage was for that program.


 Using FRE(-3) and Expanded Memory
 If expanded memory is not available, FRE(-3) generates the error message
 Feature unavailable.

 If you start QBX without the -E. n switch, you will be using all of the
 expanded memory available on your computer. If you start QBX with the -E. n
 switch, you can limit the amount of expanded memory available to your
 program. For example, if your computer has 5 megabytes of expanded memory
 but you want to use only 4 megabytes of expanded memory, you would start QBX
 with this command line.

 QBX -E.4096

 If you have specified 4 megabytes of expanded memory as shown above, and
 then you use 2 megabytes of expanded memory in your program, FRE(-3) will
 return 2048.

 If you are using BC to run a program with expanded memory overlays, the
 value returned by FRE(-3) is based on the total amount of expanded memory
 available. (When using overlays, you cannot limit the amount of expanded
 memory used by your program.)

 For more information on using expanded memory, see "Memory Management for
 QBX" in  Getting Started.


 Note

 FRE(-2) returns meaningful values only when a program is executing. Values
 returned by FRE(-2) are not accurate when the function is called from the
 Immediate window, during program tracing, or when monitoring a variable.


 Example

 The following example demonstrates use of the  FRE function to report the
 availability of memory resources. It also uses the  STACK function to
 allocate stack space.

 DECLARE SUB MakeSubString ()
 DECLARE SUB Printit (A$)
 DECLARE SUB Recursive (n!)
 PRINT "Remaining space to begin with is."
 CALL Printit(A$)
 String1$ = STRING$(32767, 90)' Create a 32K string.
 PRINT " The remaining space after creating a 32K far string is."
 CALL Printit(String1$)
 MakeSubString ' Make a substring and give report.
 PRINT "The remaining space after returning from a SUB is."
 CALL Printit(String2$)
 n = 50 ' Do 50 recursive calls to a SUB procedure.
 CALL Recursive(n)
 STACK (2048)
 PRINT "After allocating 2K for the stack, the space is."
 CALL Printit(A$)
 n = 50 ' Do another 50 recursive calls to a SUB procedure.
 CALL Recursive(n)
 'Dimension a 1001-element dynamic array in EMS.
 REDIM A%(999)
 PRINT "After dimensioning a 1000-element integer array, the space is."
 CALL Printit(A$)
 PRINT "After dimensioning a second 1000-element integer array."
 CALL Printit(A$)

 PRINT "Stack reset to default value. "; STACK

 SUB MakeSubString
 SHARED String1$
     String2$ = STRING$(32767, 90)
     PRINT "The space remaining after creating a 32K sub string is."
     CALL Printit(String1$)
 END SUB

 SUB Printit (A$)
     PRINT . PRINT "Far Memory"; TAB(15); "Stack"; TAB(25);
     PRINT "String Segment";TAB(45);"Temporary Segment";TAB(65);"EMS Memory"
     PRINT FRE(-1); TAB(15); FRE(-2); TAB(25); FRE(A$); TAB(45); FRE("")
     PRINT TAB(65); FRE(-3); "K"
 END SUB

 SUB Recursive (n)
 SHARED String1$
     n = n - 1
     IF n = 0 THEN
         PRINT "The remaining space after 50 recursive calls is."
         CALL Printit(String1$)
         EXIT SUB
     ELSE
         CALL Recursive(n)
     END IF
 END SUB